Manejo de amount y balance en la integración por API

💡 Recuerda que primero debes configurar tu proyecto para trabajar con saldo pendiente. Si aún no lo hiciste, haz clic aquí para ver cómo.

1. Haz clic en el ícono de Ajustes (engrane ⚙️), ubicado en la esquina superior derecha del dashboard.

2. Ingresa en la sección Integraciones.

3. En la parte inferior izquierda, selecciona Configuraciones avanzadas.

4. Verás dos opciones: elige Trabajar con órdenes de pago (con envío de saldo pendiente).

5. Confirma la operación.

Interfaces disponibles para la carga de datos

Moonflow permite diferentes maneras de trabajar con saldo:

1. Manejo con amount y balance en órdenes de pago (más recomendado)
Esta es la opción más completa. Envías a Moonflow todas las cuotas del crédito, con su amount (monto original), balance (saldo pendiente) y dueDate (fecha de vencimiento). Solo tienes que actualizar el balance cuando haya pagos parciales, mora o refinanciaciones.

2. Carga por pagos
En esta opción, no actualizas el balance directamente. En su lugar, envías los pagos realizados por el cliente, y Moonflow calcula internamente el saldo pendiente, con base en el amount de cada cuota menos los pagos recibidos. Para eso, es necesario integrar una tercera interfaz: la de registro de pagos.

Cuando trabajas con la carga de órdenes de pago a través de API en Moonflow, es clave que sepas cómo enviar correctamente los campos amount y balance. Esto afecta directamente las estrategias de cobranza y el rendimiento de los modelos automáticos de la plataforma.

¿Qué significan estos dos campos?

amount: Es el monto total original de la cuota o deuda. Debe incluir capital, intereses pactados desde el comienzo con el cliente, etc. No deberías sumar mora en este campo.

Ejemplo: si la deuda original era de 100 USD + 2 USD de intereses pactados desde el comienzo, el amount es 102.

balance: Es el saldo pendiente a pagar de esa cuota o deuda. Si la cuota tiene mora acumulada o pagos parciales, este valor puede ser distinto al amount.

Ejemplo: si el cliente debe 102 USD + 5 USD de mora, el balance es 107.

Buenas prácticas

No alteres el amount original con mora o recargos. Mantener el valor original ayuda a conservar coherencia con los contratos y el plan de pagos.
Actualiza solo el balance cuando haya mora, pagos parciales o descuentos. Si el saldo quedó en cero, es fundamental cargarlo en la plataforma para que se detengan las comunicaciones automáticas por esa deuda.
Conserva todo el historial del crédito. Carga siempre el plan completo de cuotas desde el inicio. No elimines cuotas pagadas ni créditos cerrados, y si necesitas actualizar, asegúrate de modificar correctamente el balance.

Ejemplo de estructura correcta

Errores comunes que debes evitar

Cargar mora en el amount en lugar de en el balance.
Enviar balance menor a cero.
No enviar las cuotas pagadas.
Borrar órdenes sin justificación.

⚠️ Para proyectos con saldo por órdenes de pago, debes tener activada esa configuración desde Ajustes > Integraciones > Configuración avanzada > Órdenes de pago (con envío de saldo pendiente).

Y si vas a modificar el balance, asegúrate de hacerlo por API con:

¿Qué errores puede devolver la API al momento de realizar envíos de datos?

Error 500: ocurre cuando algo falla en el servidor al procesar la solicitud. Es un error interno que no depende de los datos que enviaste.

Error 401: ocurre si el token no es válido.

Error 403: aparece cuando se alcanzó el límite de uso o no se tiene acceso al endpoint.

Error 409: indica un conflicto con los datos enviados.

💡 Aprende más sobre la integración mediante API accediendo a los siguientes recursos:

🚀 Artículo: Integración mediante API.

🚀 Artículo: Procesamiento de datos: Online vs Batch.

🚀 Artículo: Cargar variables auxiliares al crear un batch por API.

🚀 Artículo: Acceder a las credenciales del API de Moonflow.